package com.liyong.pullorder.sdk.dto;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.math.BigDecimal;
import java.util.Date;
import java.util.List;
import java.util.Map;

/**
 * @author 葡萄味的萝卜
 * @date 2025/10/21 12:13
 *
 * 标准化订单数据传输对象
 *
 * 核心作用：定义统一的订单数据模型，为下游系统提供洁净、标准化的数据源
 * 设计目标：收敛各平台差异，输出统一格式的订单数据
 *
 * 数据标准化：
 * - 字段命名统一：使用英文驼峰命名
 * - 数据类型统一：金额使用BigDecimal，时间使用Date
 * - 枚举值统一：状态、类型等使用标准枚举
 * - 扩展性：通过extraFields保留平台特定信息
 *
 * 应用场景：
 * - 订单同步到ERP系统
 * - 库存管理系统
 * - 财务结算系统
 * - 数据分析平台
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class StandardOrderDto {
    /**
     * 平台订单ID - 各平台原始订单编号
     * 作用：用于订单去重、问题追踪、对账等
     * 要求：非空，唯一标识
     */
    private String platformOrderId;

    /**
     * 平台编码 - 标识订单来源平台
     * 如：HUAWEI（华为）、HONOR（荣耀）、ZJMOBILE（浙江移动）
     * 作用：数据分类、统计分析和问题定位
     */
    private String platformCode;

    /**
     * 订单状态 - 标准化的订单状态
     * 标准状态：PAID(已支付)、SHIPPED(已发货)、COMPLETED(已完成)、CANCELLED(已取消)
     * 作用：驱动下游业务流程，如发货、结算等
     */
    private String orderStatus;

    /**
     * 订单金额 - 使用BigDecimal保证精度
     * 单位：元，保留2位小数
     * 作用：财务结算、销售统计
     */
    private BigDecimal orderAmount;

    /**
     * 币种 - 默认CNY（人民币）
     * 作用：支持多币种订单，国际化扩展
     */
    private String currency;

    /**
     * 订单创建时间 - 平台侧订单创建时间
     * 作用：时效性统计、业务时序分析
     */
    private Date orderTime;

    /**
     * 支付时间 - 订单支付成功时间
     * 作用：财务对账、支付时效分析
     */
    private Date payTime;

    /**
     * 客户姓名 - 收货人姓名
     * 作用：物流发货、客户服务
     */
    private String customerName;

    /**
     * 客户电话 - 收货人联系电话
     * 作用：物流联系、客户服务
     * 格式：11位手机号，已做标准化清洗
     */
    private String customerPhone;

    /**
     * 收货地址 - 完整的收货地址
     * 作用：物流配送、区域分析
     */
    private String shippingAddress;

    /**
     * 订单商品列表 - 订单包含的商品明细
     * 作用：库存扣减、商品销售统计
     */
    private List<OrderItemDto> items;

    /**
     * 扩展字段 - 保留平台特定信息
     * 作用：兼容各平台特殊字段，避免数据丢失
     * 示例：平台优惠信息、特殊标识、业务扩展字段等
     */
    private Map<String, Object> extraFields;

    /**
     * 数据创建时间 - 拉单系统创建记录的时间
     * 作用：系统监控、数据同步时效分析
     */
    private Date createTime;

    /**
     * 数据更新时间 - 最后更新时间
     * 作用：增量同步、数据变更追踪
     */
    private Date updateTime;
}
